SPACE 2

home *** CD-ROM | disk | FTP | other *** search

/ SPACE 2 / SPACE - Library 2 - Volume 1.iso / program / 665 / install.doc < prev next >

Wrap

Text File | 1992-12-10 | 30.5 KB | 700 lines

Welcome to Ian's Heat-and-Serve C! This release is version 1.40, dated 12/10/92 *************************************************** * THIS IS A MODIFIED VERSION OF SOZOBON C! * * * * This version has been customized by Ian Lepore, * * and is NOT an official release of Sozobon, Ltd. * * Please do NOT direct any bug reports or support * * questions for this release to the good folks at * * Sozobon...if anything goes wrong, it's * * Not Their Fault. * *************************************************** CONTENTS 1.0 Introduction 1.1 Quick Start - Read this at the very least! 1.2 Overview of Heat-and-Serve C 2.0 Installation 2.1 Upgrading from a prior release 2.2 Notes for Floppy Disk Installation 2.3 The INSTALL Program 2.4 The GEMENV Program 2.5 Desktop Installation Procedure 2.6 CLI Installation Procedure 3.0 In Case of Difficulties 3.1 Trouble with MAKE 3.2 Trouble with Environment Variables 4.0 Roadmap (Directory and File List) 5.0 Credits and disclaimers 1.0 Introduction Welcome to Ian's Heat-and-Serve C (HSC). I know this document is pretty long, but there's a lot in here you don't need to know unless you have trouble; installation is not a hard process at all. Please read the Quick Start notes that follow, then proceed from there. 1.1 Quick Start If you are upgrading from an earlier Heat-and-Serve release, and are familiar with the general installation procedure, please proceed to section 2.1, "Upgrading from a prior release." Nothing in the rest of this document has changed significantly for you. If this is a first-time install, I strongly recommend that you at least browse through the sections in chapter 2. If you just aren't the document-reading type, you're in luck. Most of the installation process is handled by the INSTALL program. If you're using the GEM desktop, the INSTALL program does everything for you. If you use a CLI, you have to set some environment variables by hand in your CLI. The INSTALL program can run both in GEM and non-GEM modes. It gives you several opportunities to quit before it starts installing the compiler. Just unpack everything from the distribution archive into the same directory, run INSTALL, follow its directions, reboot your system to install GEMENV and DESKTOP.INF, and you're up-and-running. I still think you should browse chapter 2 before installing, though. 1.2 Overview of Heat-and-Serve C I have dubbed this offering 'Heat-and-Serve C' to avoid further confusion with Sozobon C's ongoing releases. Because it's derived from Sozobon C, you'll still see many references to Sozobon, especially in directory names and such. Besides avoiding confusion, I feel that this compiler has diverged enough from the original to warrant a separate name. Unlike previous Sozobon releases, this one virtually installs itself, and it works right away, without the need for a lot of customization. In addition to the easier installation, this release differs from the original Sozobon C v1.0 and 1.2 releases in the following ways: - Many bug fixes over prior releases. - A new version of GemFast GEM support, with many enhancements. - The compiler now speaks English instead of technish when reporting errors. (LD still tends to be cryptic). - A desktop-friendly MAKE utility is included, as well as other assists for the desktop user. - The compiler pieces and MAKE utility are smarter about where to look for files in the absence of PATH= information. - Several code generation bugs were fixed in the compiler. Also, several ANSI features were added, such as concatenation of adjacent string literals. - The TOP optimizer is vastly improved in terms of the peephole optimizations it does. - The compiler controller (CC) program now knows how to use a ramdisk to hold intermediate files, for better performance. (Floppy disk users especially benefit from this.) - Lots of performance tweaks; in particular, intelligent I/O buffering has been added to the compiler pieces, and the assembler is 50-100% faster. - All libraries and runtime supports are included in the distribution, including the GemFast libraries for GEM programming, and a variety of runtime startup files for different environments. - This release does NOT include source code (except for the runtime startup files and example programs.) 2.0 Installation HSC is supplied as a single archive file which contains everything needed to set up the compiler and begin writing programs immediately. There is no need for you to obtain other support files from your network or BBS. When unpacking the distribution archive (the one that contained this file), it is important that all the files that came out of it remain together in the same folder. If any of the files are missing, the installation program may not be able to perform all the installation steps (it will whine at you). When the distribution archive is unpacked, the following files emerge: INSTALL.DOC - This document. INSTALL.PRG - The installation utility. GEMENV.PRG - Environment variable manager. HSBIN140.PDF - The compiler itself, in packed format. HSDOC140.PDF - The full documentation, in packed format. HSXMP140.PDF - The example source code, in packed format. After reviewing the installation notes below, all you need to do is run INSTALL.PRG, which installs and configures the compiler. The installation program uses a GEM interface when it detects that GEM is active on your system. (If you normally boot your machine straight into a CLI without allowing GEM to initialize, the INSTALL program detects that and runs in a text-only mode.) The compiler itself does not require GEM or desktop usage once it's installed. The install program will prompt you for which installation steps you wish to run, and which drives or hard disk partitions you wish to install the parts of the compiler on. There are three separate Packed Data Files, to accommodate floppy disk users. It is assumed that hard disk users will generally unpack all three data files to the same partition, so the INSTALL program will pre-set its buttons for that situation. This is optional, however. The files unpacked from the HSBINxxx.PDF file MUST ALWAYS remain together on the same drive, but the documentation and examples can go anywhere. The packed data files will require disk space to unpack as follows: HSBIN140.PDF = 580 KBytes HSDOC140.PDF = 512 KBytes HSXMP140.PDF = 138 KBytes ---------------------------- Total = 1230 KBytes Unpacked Note that when names of the form "x:\PATH" appear in the notes below the 'x' should be filled in with the drive onto which you unpacked the compiler (the HSBINxxx.PDF file). 2.1 Upgrading from a prior release If you're doing a first-time install, you can skip this section. The process for upgrading is identical to that of initially installing, except that the GEMENV and DESKTOP.INF parts of the installation can be skipped. This version of HSC requires about 400k more disk space than prior releases. The increases are primarily in the new GemFast documentation, and the example code. When running INSTALL to upgrade to a newer version, every file in the standard distribution will be overwritten without prompting. If you have modified any of your header or library files, they will be replaced. If you have added new files to the \sozobon directory tree, they will remain untouched. Either before or after running INSTALL.PRG to do the upgrade, you may delete the following obsolete files from \SOZOBON\DOC: GEMFBIND.DOC GEMF_V17.DOC GEMUTIL.DOC GEMXTEND.DOC They have been superceded by two new files with different names. If you are a GEM programmer, you MUST read GEMFINST.DOC and GEMFAST.DOC before trying to use HSC v1.40. Changes in GemFast make it crucial for you to recompile your existing code before trying to link it with GemFast v1.8 libraries. 2.2 Notes for Floppy Disk Installation If you are installing to a hard disk, you can skip this section. The floppy disk installation procedure has been completely revamped for the 1.33 (and later) versions. You no longer need two floppy drives or a huge ramdisk to perform the installation. The process now works with a single double-sided drive, as long as you have at least as much free RAM in your system as the largest PDF installation file. As the installation proceeds, you will be prompted to insert the input and output disks as needed. I've tried to keep disk swaps to a minimum. Before starting the installation, unpack all the distribution files to a floppy disk. (The PDF files, and the INSTALL and GEMENV programs must all be on the same floppy disk when you start INSTALL.PRG.) Next, format two double-sided floppy disks. One disk will hold the compiler itself, and the other will hold the documentation and example files. On the compiler disk, create an AUTO folder, and copy your favorite auto programs into it. Also, put a copy of your usual DESKTOP.INF file onto the compiler disk. The other disk does not need an AUTO folder or DESKTOP.INF. After preparing your floppy disks, Follow either the Desktop or CLI procedure below, depending on the way you intend to use HSC. 2.3 The INSTALL Program This section describes exactly what INSTALL.PRG does to your disk. As of v1.33, the INSTALL program does not require GEM to function. If you normally boot your machine into a CLI before GEM is initialized, INSTALL will detect this and run in a text- based mode instead of using GEM dialogs to interact with you. The basic operation of the program in non-GEM mode is the same, except that the GEMENV and DESKTOP.INF updates are not done. The following discussion assumes GEM mode; in CLI mode you will be prompted to enter a drive letter in place of clicking on a button, and so on. You can force the program to run in non-GEM mode by supplying a parameter on the command line when you run it. (Any character(s) on the command line will do.) INSTALL initially presents a dialog box that describes the steps of the installation, and has a drive button next to each step. You may click on the drive button for any step to change the target drive or set that step to be bypassed completely. After setting the drive buttons appropriately, click on the PROCEED button to run the installation steps which were not set for bypass. Even after clicking on PROCEED, you will be prompted for one more chance to stop the installation before any data is unpacked or any of your system files are modified. The install program takes the following steps (assuming none are bypassed): 1. It installs the compiler. This step unpacks the contents of HSBINxxx.PDF to the indicated drive. The unpacking process will create a \SOZOBON folder in the root of the target drive, and will create other folders within \SOZOBON. When this option is active (ie, not bypassed), you will be prompted for two additional parameters after clicking on PROCEED, the I/O buffer size, and the device for temporary files. Both of these options are entered via GEM dialog boxes which contain a description of the parameters and recommended settings. 2. It installs the documentation. This step unpacks the contents of HSDOCxxx.PDF to the indicated drive. 3. It installs the example programs. This step unpacks the contents of HSXMPxxx.PDF to the indicated drive. 4. It installs GEMENV.PRG into the AUTO folder on the indicated drive. The GEMENV program is described below. If you are using the standard GEM desktop, or DCDesktop, you must run this step. If you are using a CLI, GEMINI, NeoDesk, or other alternate desktops that have builtin support for environment variables, you may bypass this step, and manually configure your env variables to the values described in the CLI installation. 5. It modifies the DESKTOP.INF file on the indicated drive to install MAKE.TTP as the application to handle double-clicks on files ending in .MAK. If you are using the GEM desktop or DCDesktop, you may run this step, or take the corresponding action manually. If you are running different alternate desktop, you will need to follow whatever procedure exists for that desktop to install an application to handle double-clicks on .MAK files. If you will be using HSC only from a CLI, this step may be bypassed. Note that during the installation of GEMENV and modification of your DESKTOP.INF file, the install program will rename your existing ROOT.ENV or DESKTOP.INF file (if any) to end in .BAK, to provide you with a quick recovery if anything goes wrong. The change to DESKTOP.INF to install MAKE as the application for *.MAK files is described in detail in \SOZOBON\DOC\ST_MAKE.DOC. 2.4 The GEMENV Program The GEMENV program installed in step 4 is a TSR that gives the desktop the ability to handle environment variables. It is described in detail in \SOZOBON\DOC\GEMENV.DOC. It is a 'passive TSR'; that is, it only allocates a 1k data area in memory and then terminates leaving that memory resident. It leaves no hooks in the operating system after the desktop is started. The memory is used to store environment variables. You may also double-click on GEMENV.PRG from the desktop at any time; online help is available in the program. If you decide to run without GEMENV for some reason, it will probably be necessary to edit the x:\SOZOBON\BIN\MAKE.INI file and uncomment the statements in the .INICMDS section. In this case, your best bet is to install everything on your C: drive, or always run the compiler only from the drive it is installed on. See the 'Trouble with MAKE' section, below, for more hints on how to run without GEMENV. (Your best bet, by far, is to use GEMENV.) When you use an alternate desktop, or other programs which run from AUTO but take effect after the desktop is started, it may be necessary to ensure GEMENV runs early in the AUTO folder processing. This is not a problem with GEMENV, but rather a side effect of the way alternate desktop programs install themselves into the same system vector that GEMENV uses to borrow control from the system for a moment just before the desktop starts. 2.5 Desktop Installation Procedure To use HSC from the desktop, perform the following steps: 1. Unpack the entire distribution archive to any disk you want, but unpack all the files to the same folder. 2. Run INSTALL.PRG. See the description in section 2.3, above. For use from the GEM desktop, you should generally allow all the installation steps to run. 3. At this point, if you are using an alternate desktop, take whatever manual steps are necessary to correspond to the INSTALL.PRG steps that were bypassed. (IE, configure your environment variables as described in the CLI installation, below, and install MAKE.TTP as the application for .MAK files). 4. Reboot, to make the GEMENV program and new DESKTOP.INF file install themselves in the system. 5. Open a window on \SOZOBON\EXAMPLES and double-click on MAKEFILE.MAK. This will run a series of tests on the compiler. See the 'In Case of Difficulties' section, below, if the tests don't work. Some of the tests create GEM programs, but they are not run from the makefile because GEM programs can't be started from a .TTP. After they are compiled, just double-click on them from the desktop. (The GEM programs are generated into their own folders inside the EXAMPLES folder.) 2.6 CLI Installation Procedure To use HSC from a command shell (such as Gulam), perform the following steps: 1. Unpack the entire distribution archive to any disk you want, but unpack all the files to the same folder. 2. Run INSTALL.PRG. See the description in section 2.3, above. To use the compiler from a command shell, you should generally set the GEMENV and DESKTOP.INF installation steps to BYPASS. 3. Using whatever method is provided by your CLI, set the following environment variables: PATH=C:\;x:\SOZOBON\BIN\ INCLUDE=x:\SOZOBON\INCLUDE\ LIB=x:\SOZOBON\LIB\ BUFSIZE=4096 TMP=r:\ The TMP variable is optional. If you have a fast device such as a ramdisk, you can use it for intermediate files by putting its drive letter in the TMP= variable. For the PATH variable, the path listed above may be added to your existing path list, separated with commas or semicolons. The trailing slash on the pathnames is optional -- include them or not based on what your other software prefers. (Note that TOS 1.0 GEM *really* likes to see C:\ as the first path in the PATH= list! If you use TOS 1.0, it's best to ensure that C:\ is always first.) The BUFSIZE value may be set to anything between 1024 and 32512, in multiples of 512. If you have the memory to spare, 8k or 16k works well. 4. Enter whatever command needed to make \SOZOBON\EXAMPLES the current directory, and type MAKE. This will run a series of tests on the installation. Part of the testing includes compiling GEM programs, but they are not run automatically from the makefile. 3.0 In Case of Difficulties Most problems with HSC come from two sources: 1) trouble in your makefile, and 2) the compiler can't find its support files. 3.1 Trouble with MAKE For makefile troubles, about the best advice I can offer is to read MAKE.DOC and ST_MAKE.DOC about 20 times, and rely heavily on the stuff in the examples directory. Remember that the '-p' and '-d' MAKE options can be useful in debugging problems in your makefiles. Also remember that if you are running MAKE from the desktop, you can hold down either SHIFT key while clicking on the .MAK file to get prompted for options. If double-clicking on a .MAK file doesn't cause MAKE.TTP to run, double-check your DESKTOP.INF file (see ST_MAKE.DOC for details on the DESKTOP.INF installation line). If MAKE.TTP starts, but warns that it can't find MAKE.INI, check your PATH= environment variable, or create a C:\SOZOBON\BIN dir and put MAKE.INI in there. If make runs, but reports trouble finding the HSC compiler programs, check the contents of the MAKE.INI file, especially the pathnames in the .INICMDS area. 3.2 Trouble with Environment Variables When the compiler has trouble finding its support files, it almost always comes down to trouble with your environment variables. Since the GEM desktop doesn't directly support env vars, this used to be 99% of everyone's Sozobon troubles. With the new GEMENV program, this trouble basically disappears. Even without help from GEMENV, this release of HSC is pretty good at finding its pieces. It will search in the \SOZOBON path of the current drive, and if that fails, it will look for C:\SOZOBON paths. This implies that if you don't want to use GEMENV for some reason, you can always install the compiler on the C: drive and expect things to work no matter what drive your source code is on. To make debugging the path-related problems a little easier, a program is included in the \SOZOBON\SPECIAL directory, called NAMETRAK.PRG. When you run this program, it installs itself into the DOS vector and logs to the printer all file-related activity. Often, by installing NAMETRAK and then running the HSC compiler, you can find out where it is looking for files and either move everything to there (a kind of crude solution!) or make adjustments in your env vars. You must reboot your machine to de-install the NAMETRAK program. Another debugging program, SHOWENV.TOS, simply displays to the screen the contents of all the environment variables currently in effect. Whatever you see here is what the compiler and MAKE will see when they are run. This is a normal program, not a TSR. 4.0 Roadmap This section provides an overview of the HSC directory structure and points out some important files. When the distribution archive is unpacked, it creates the following directory structure: drive: \SOZOBON - The Sozobon root, no files here. \BIN - The executables. \INCLUDE - The C header files for #include. \LIB - The runtime libs and startup files. \DOC - Documentation for everything. \EXAMPLES - Example programs. \SPECIAL - Desktop assists and troubleshooting. \SOZOBON\BIN This directory contains all the executables to run HSC, including MAKE, and including the MAKE.INI file required to supply MAKE with rules appropriate to compiling HSC programs. If you have a consolidated \BIN directory elsewhere in your system, and you feel brave, you can copy the contents of the \SOZOBON\BIN directory to your single \BIN directory, adjust your PATH= statement accordingly, and run. (This is what I do.) However, this sort of messing around with the HSC structure is not for the faint-hearted or easily-frustrated programmer. \SOZOBON\INCLUDE This directory holds all the header files for HSC (except those you write yourself for your own applications -- those would be in the same directory as the application source code). The files in this directory are originally from the dLibs12 distribution package that corresponds to HSC, and from the GemFast GEM programming library package. If you have your own system of library files and headers, or if you modify any of the delivered headers, it is recommended that you create a new folder for them. If you do this, set the INCLUDE= environment variable to contain the pathname of your folder followed by the \SOZOBON\INCLUDE folder (separate the two pathnames with a semicolon). Keeping this separation will ensure that you don't lose your modifications when upgrading to a new version of HSC or dLibs. \SOZOBON\LIB This directory contains the runtime libraries that are linked with your program by LD in the final stage of a compile. The dlibs.a file contains the bulk of the runtime support. The libm.a file contains floating-point math support, and is needed only when you use floating point variables in your program. The vdifast.a and aesfast.a files contain the GEM runtime libraries, they are needed only when you write GEM programs. In addition, the runtime startup files that are linked ahead of your program are located here, including the source code. The startup files, and the situations they are good for, are as follows: DSTART.O - Standard runtime startup, for use with dlibs.a. This is required if you use stream I/O (fopen, fclose, printf, etc). APSTART.O - A stripped-down startup file useful for GEM programming. This startup will give you command-line arguments (argc/argv), but will not automatically open or close stream I/O. The argc/argv support in this startup file does NOT include XARGS or ARGV support! MINSTART.O - A very small startup file useful primarily for desk accessories and GEM programs that don't need argc/argv. This startup can also be used to create a program that runs as either a .PRG or .ACC when you rename the program file. The notes about extended or modified files under \SOZOBON\INCLUDE above apply to this directory as well. It is safer to create a new directory for your extensions to prevent troubles when upgrading. If you do this, be sure to modify the LIB= env var. \SOZOBON\DOC This directory contains all the documentation in the HSC system including a copy of the document you are reading now. The documents are: SOZOBON.DOC The docs originally released with Sozobon, but modified a bit for this release. This doc may contain references for tools not included in this release because they are rarely used. This is where you'll find references for all the command-line options of the various compiler pieces. DLIBS.DOC The runtime library reference. This documents all the typical C functions such as fopen(), strcpy(), and so on. GEMFAST.DOC The GemFast library function reference and programming guide. GEMFINST.DOC GemFast installation and portability notes. MAKE.DOC Documents for the MAKE utility. MAKE.DOC is a ST_MAKE.DOC general overview of MAKE for those unfamiliar with it. ST_MAKE.DOC describes implementation and ST-related features, and has the STMAKE revision history notes. GEMENV.DOC Docs for the GEMENV TSR program, and some discussion of environment variables in general. VRSN_xxxx.DOC Cumulative release notes for everything. \SOZOBON\EXAMPLES This directory contains example source code and makefiles used in testing the installation of the compiler. The source code in this directory is all public domain, and may be copied into your own programs at will. Each of the example programs listed below has a makefile associated with it, and in some cases, custom header files and RSC files. The example programs are: HELLO.C The obligatory Hello World program. FPMATH.C Some tests using floating-point math. MINICOLR.C An example that runs as an accessory or program. WINDXMP2.C A GEM program with a window and some neat stuff. FORMDEMO.C A GEM program that uses all the cool new GemFast dialog functions. BROWSE.C A GEM program that uses manages multiple windows and demonstrates handling scrolling windows. MAKEFILE.MAK A makefile which calls MAKE recursively to compile all the sample programs. 5.0 Credits and Disclaimers This version of HSC is released on an as-is basis, under the terms of the original Sozobon, Ltd. copyright, which still applies. This is a modified version of Sozobon C, but that does not imply any loss or reduction of rights to the original copyright holders. The authors assume no responsibility for the consequences of using this software, including, but not limited to, responsibility for your mental health. No warranties of any sort, express or implied, are made about this software or its suitability for a particular purpose. Besides, I ain't got no money, so suing me would be a real waste of your time. The original Sozobon C was created by Tony Andrews, Johann Ruegg, and Joe Treat. This modified version was done by Ian Lepore. The dlibs runtime library was done by Dale Schumaker. Beta testing of this modified release was done by Bob Goff, Mike Dorman, Steve Yelvington, Scott Bigham, and probably others who've I've forgotten about since this release has been lying dormant for 6 months now due to extreme laziness (and a being a bit busy) on my part. I want the world to be well aware that a lot effort by a lot of folks went into this project before I ever got my hands on it. Without them, it wouldn't have been possible. Everything in this distribution package which is wholly my own work (GemFast, GEMENV, STMAKE, and the example source code) is hereby placed into the public domain. You may copy, modify, distribute, or otherwise use these portions of the work in any way you please, including their inclusion into other works, public domain or commercial. In particular, I'd like to see GEMENV get wide distribution. If you do modify and redistribute any of my works, I'd appreciate it if they are clearly marked as modifications, so I won't go nuts trying to support something that's been customized. This release of HSC is being distributed initially via the BIX online system, and I will do my best to provide what support I can on BIX. I'm not consitantly available on any of the other networks at this time. Other than the fact that I hang out there, there is no official connection between BIX and this software, however. (For you internet'ers: you may be able to reach me at "ianl@bix.com". The internet mail gateway isn't available yet, but I feel certain that it will become available sometime soon. I have no reason to feel that way, other than that GVC management at BIX has been doing a good job of upgrading the system lately. If it doesn't work this week, try again next week, and so on until it gets through.) Oh--and in case you ever wondered: Sozobon is No Bozos, backwards. - Ian Lepore (BIX userid 'ianl') Moderator, BIX atari.st and c.language conferences. 12/10/92 (end of document) ə